/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.beanutils;
import java.util.Map;
import java.util.WeakHashMap;
/**
* An instance of this class represents a value that is provided per (thread)
* context classloader.
*
* <p>Occasionally it is necessary to store data in "global" variables
* (including uses of the Singleton pattern). In applications which have only
* a single classloader such data can simply be stored as "static" members on
* some class. When multiple classloaders are involved, however, this approach
* can fail; in particular, this doesn't work when the code may be run within a
* servlet container or a j2ee container, and the class on which the static
* member is defined is loaded via a "shared" classloader that is visible to all
* components running within the container. This class provides a mechanism for
* associating data with a ClassLoader instance, which ensures that when the
* code runs in such a container each component gets its own copy of the
* "global" variable rather than unexpectedly sharing a single copy of the
* variable with other components that happen to be running in the same
* container at the same time (eg servlets or EJBs.)</p>
*
* <p>This class is strongly patterned after the java.lang.ThreadLocal
* class, which performs a similar task in allowing data to be associated
* with a particular thread.</p>
*
* <p>When code that uses this class is run as a "normal" application, ie
* not within a container, the effect is identical to just using a static
* member variable to store the data, because Thread.getContextClassLoader
* always returns the same classloader (the system classloader).</p>
*
* <p>Expected usage is as follows:<br>
* <pre>
* public class SomeClass {
* private static final ContextClassLoaderLocal global
* = new ContextClassLoaderLocal() {
* protected Object initialValue() {
* return new String("Initial value");
* };
*
* public void testGlobal() {
* String s = (String) global.get();
* System.out.println("global value:" + s);
* buf.set("New Value");
* }
* </pre>
* </p>
*
* <p><strong>Note:</strong> This class takes some care to ensure that when
* a component which uses this class is "undeployed" by a container the
* component-specific classloader and all its associated classes (and their
* static variables) are garbage-collected. Unfortunately there is one
* scenario in which this does <i>not</i> work correctly and there
* is unfortunately no known workaround other than ensuring that the
* component (or its container) calls the "unset" method on this class for
* each instance of this class when the component is undeployed. The problem
* occurs if:
* <ul>
* <li>the class containing a static instance of this class was loaded via
* a shared classloader, and</li>
* <li>the value stored in the instance is an object whose class was loaded
* via the component-specific classloader (or any of the objects it refers
* to were loaded via that classloader).</li>
* </ul>
* The result is that the map managed by this object still contains a strong
* reference to the stored object, which contains a strong reference to the
* classloader that loaded it, meaning that although the container has
* "undeployed" the component the component-specific classloader and all the
* related classes and static variables cannot be garbage-collected. This is
* not expected to be an issue with the commons-beanutils library as the only
* classes which use this class are BeanUtilsBean and ConvertUtilsBean and
* there is no obvious reason for a user of the beanutils library to subclass
* either of those classes.</p>
*
* <p><strong>Note:</strong> A WeakHashMap bug in several 1.3 JVMs results in
* a memory leak for those JVMs.</p>
*
* <p><strong>Note:</strong> Of course all of this would be unnecessary if
* containers required each component to load the full set of classes it
* needs, ie avoided providing classes loaded via a "shared" classloader.</p>
*
* @see java.lang.Thread#getContextClassLoader
* @author Eric Pabst
*/
public class ContextClassLoaderLocal {
private Map valueByClassLoader = new WeakHashMap();
private boolean globalValueInitialized = false;
private Object globalValue;
/**
* Construct a context classloader instance
*/
public ContextClassLoaderLocal() {
super();
}
/**
* Returns the initial value for this ContextClassLoaderLocal
* variable. This method will be called once per Context ClassLoader for
* each ContextClassLoaderLocal, the first time it is accessed
* with get or set. If the programmer desires ContextClassLoaderLocal variables
* to be initialized to some value other than null, ContextClassLoaderLocal must
* be subclassed, and this method overridden. Typically, an anonymous
* inner class will be used. Typical implementations of initialValue
* will call an appropriate constructor and return the newly constructed
* object.
*
* @return a new Object to be used as an initial value for this ContextClassLoaderLocal
*/
protected Object initialValue() {
return null;
}
/**
* Gets the instance which provides the functionality for {@link BeanUtils}.
* This is a pseudo-singleton - an single instance is provided per (thread) context classloader.
* This mechanism provides isolation for web apps deployed in the same container.
* @return the object currently associated with the context-classloader of the current thread.
*/
public synchronized Object get() {
// synchronizing the whole method is a bit slower
// but guarantees no subtle threading problems, and there's no
// need to synchronize valueByClassLoader
// make sure that the map is given a change to purge itself
valueByClassLoader.isEmpty();
try {
ClassLoader contextClassLoader = Thread.currentThread().getContextClassLoader();
if (contextClassLoader != null) {
Object value = valueByClassLoader.get(contextClassLoader);
if ((value == null)
&& !valueByClassLoader.containsKey(contextClassLoader)) {
value = initialValue();
valueByClassLoader.put(contextClassLoader, value);
}
return value;
}
} catch (SecurityException e) { /* SWALLOW - should we log this? */ }
// if none or exception, return the globalValue
if (!globalValueInitialized) {
globalValue = initialValue();
globalValueInitialized = true;
}//else already set
return globalValue;
}
/**
* Sets the value - a value is provided per (thread) context classloader.
* This mechanism provides isolation for web apps deployed in the same container.
*
* @param value the object to be associated with the entrant thread's context classloader
*/
public synchronized void set(Object value) {
// synchronizing the whole method is a bit slower
// but guarentees no subtle threading problems
// make sure that the map is given a change to purge itself
valueByClassLoader.isEmpty();
try {
ClassLoader contextClassLoader = Thread.currentThread().getContextClassLoader();
if (contextClassLoader != null) {
valueByClassLoader.put(contextClassLoader, value);
return;
}
} catch (SecurityException e) { /* SWALLOW - should we log this? */ }
// if in doubt, set the global value
globalValue = value;
globalValueInitialized = true;
}
/**
* Unsets the value associated with the current thread's context classloader
*/
public synchronized void unset() {
try {
ClassLoader contextClassLoader = Thread.currentThread().getContextClassLoader();
unset(contextClassLoader);
} catch (SecurityException e) { /* SWALLOW - should we log this? */ }
}
/**
* Unsets the value associated with the given classloader
* @param classLoader The classloader to <i>unset</i> for
*/
public synchronized void unset(ClassLoader classLoader) {
valueByClassLoader.remove(classLoader);
}
}